COMMENT ⊗   VALID 00004 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	The FTP command is used  to transfer files between SAIL and  another network
C00025 00003	                           Multiple File Transfer
C00041 00004	                           One-line FTP transfers
C00047 ENDMK
C⊗;
The FTP command is used  to transfer files between SAIL and  another network
host.  FTP  can be used  in two-ways:  for a simple  transfer, a  single FTP
monitor command can  be typed which  contains all the  information necessary
for the  transfer, much  like a  COPY command;  if several  files are  to be
transferred, or one of the  less common protocol features must be  used, the
FTP command can  establish a connection to  a remote File  Transfer Protocol
server  program,  and  you  can then  enter  protocol  commands  to initiate
transfers.  FTP can also be used for file manipulation other  than transfers
at a remote host, e.g., directory listings, and file renaming and deleting.

Although the one-line FTP command is generally easier to use,  this document
will start with the more detailed use of the protocol commands.   The reason
for this choice  is that to use  even the one-line command  effectively, you
should understand some of the underlying protocol, which is more apparent in
the multiple command mode of using FTP.

The FTP command  is used to  set up a connection  to a remote  File Transfer
Protocol server.   It takes a  host argument like  TELNET, except that  if a
host number is used it should be in decimal; to specify a nonstandard socket
number, the syntax is host#socket.  (The normal FTP connection is  to socket
3.) Once the connection is set  up, you can enter the following  commands to
the FTP program.  Each command is a name followed by arguments  as described
below.  Only the first four letters are significant (letters beyond four are
ignored), and  commands may  be abbreviated  by enough  letters to  make the
abbreviation unique.   Note that file  specifications for remote  hosts must
follow the format conventions of  that host; they are passed on  verbatim by
the FTP.   In particular,  the case of  letters may  be significant  at some
hosts.

Note: FTP command strings sent over the control link to the remote  host are
subject to character conversion to conform with standard ASCII, as described
in  the discussion  of  the TELNET  program.   The processing  of  file data
depends on the transfer type; see the TYPE command below.

Some of the commands below  are named the same as the  corresponding command
sent over the network in accordance with the actual File  Transfer Protocol;
in some cases alternate names are also defined.  Complete information on the
protocol  is  available  in  the network  document  with  NIC  number 14333,
although there have  been several modifications  to the protocol  since that
document was written.   There is also  a "new" FTP which  is not, so  far at
least, actually in use.

We do not implement all  of the protocol options.  In particular,  we accept
only MODE S (stream)  and only STRU F  (file).  Our server accepts  MODE and
STRU commands but only with  the above arguments; our user does  not provide
any way of specifying mode or structure.

When the  connection is  first established,  our user  FTP program  tries to
negotiate an  appropriate type and  byte size with  the other  end's server.
First it sends TYPE I, and then BYTE 36.  If the latter is accepted  but the
former  was  not, it  sends  TYPE I again.   (These  commands  are explained
below.)   If  these  are not  accepted,  it  sends BYTE 8,  and  if  that is
accepted, TYPE A.  (All hosts are supposed to accept BYTE 8.)  If nothing is
accepted, the program tries again  after you give the USER command,  in case
the problem is that their server was written by an obnoxious  security freak
as at a well-known system in Cambridge, Massachusetts.

The protocol provides an abort function which can be used to stop a transfer
which  is in  progress.  This  function  can be  requested in  our  FTP user
program by typing ESC I (from a non-display, type ↑← I).  This will send the
abort command only if there is a transfer in progress.  Many servers  do not
process the abort  sequence, but they should  notice when we close  the data
connection.  You may end up, if you are doing a STOR, writing  an incomplete
file on the other system.

In the file transfer commands below, the character = can be used  instead of
either  ←  or →  as  shown, for  the  convenience of  users  at non-Stanford
terminals.

TYPE x   x is A, I,  L, P, or E,  and specifies the representation  type for
         the data.  The uses of the various types are as follows:

TYPE A   ASCII type  means that  the file to  be transferred  contains text.
         The characters in the file will be transferred to or from  the SAIL
         character  set,  as  explained  for  TELNET  connections,  and null
         characters will be ignored.   This type should be used  to transfer
         text  files   to  or   from  a  machine   with  a   different  text
         representation.  Text  files can  be transferred  to or  from other
         PDP-10 systems more efficently using image type (below) if  the few
         characters which are translated by ASCII translation are  unused in
         the file, since  our character code is  almost the same as  that of
         other PDP-10s.  ASCII transfers of local files will  also eliminate
         the E directory or SOS line numbers, if any.

ASCII    is an abbreviation for TYPE A.

TYPE I   Image type means that the  file is taken as a continuous  stream of
         bits and sent  accordingly.  The number of  bits sent at a  time is
         determined by the byte size set with the BYTE command (below).  The
         most efficient byte size for us  is 36, the size of a  PDP-10 word.
         Any  byte  size  which is  a  factor  of 36  can  be  used  with no
         difficulty, if needed to accommodate some other system.  Byte sizes
         of 8 or 32, however, cause extreme inefficiency because  some bytes
         are split between two PDP-10  words.  If you are retrieving  a file
         from an 8-bit or 32-bit system, you might want to use TYPE L (local
         byte), which uses only the  first 32 bits of each PDP-10  word, and
         can   therefore   be  implemented   using   the   normal  ILDB/IDPB
         instructions.  However, sending  a file to  such a system  in local
         byte type will lose bits 32-35 of each word.

IMAGE    is an abbreviation for TYPE I.

TYPE L   Local  byte type,  as explained  above, treats  the file  as normal
         PDP-10 bytes  of the size  specified in a  BYTE command.   For byte
         sizes which are a factor of 36, this is treated exactly the same as
         image type (above); for byte size 8 or 32 it uses only bits 0-31 of
         each PDP-10 word.   Byte size 32 is  more efficient than 8  in this
         type.

LOCAL    is an abbreviation for TYPE L.

TYPE P   ASCII print type is treated  by our system the same as  ASCII type.
         This isn't right, but the protocol is not consistent about  what to
         do.  Some people  interpret this type  as indicating that  the file
         contains FORTRAN style format control characters.

TYPE E   EBCDIC type is not  implemented here.  It is used  for transferring
         text  files  between two  IBM  systems.  To  transfer  a  text file
         between here  and an IBM  system, use TYPE A;  the IBM  system will
         translate between ASCII and their local character code as needed.

TYPE X   This command to our FTP user program does not correspond to  a real
         data type in the protocol.   Instead, it is treated as  TYPE L here
         but  tells the  other  end TYPE I.   Use  this command  if  you are
         talking to an  8-bit machine and want  to use local byte  type, but
         the other machine does not accept the TYPE L command.

BYTE n   n is  a (decimal) number  indicating the byte  size of  the network
         data connection.   Data will be  sent from one  host to  another in
         bytes of this size, for  image type and local byte  type transfers.
         ASCII transfers always use a byte size of 8.  (That is,  each 7-bit
         local character code is translated into an 8-bit network ASCII code
         and  vice versa.)   The allowable  byte sizes  are 8,  32,  and any
         factor of  36 (1,  2, 3,  4, 6, 9,  12, 18,  36).  In  general, the
         largest byte size  which will work  is the most  efficient.  (Note:
         the protocol specifies  that it is  the responsibility of  the user
         FTP  to  ensure that  8-bit  bytes are  used  for  ASCII transfers.
         Accordingly, our user FTP  program does not necessarily  transmit a
         BYTE command as soon as  the user types it; instead, the  byte size
         in the  command is remembered  for use in  binary transfers,  and a
         BYTE command is  sent to the FTP  server whenever necessary  as the
         transfer type changes.)

USER x   x is a string which the foreign host will recognize as a valid user
         description, user name, or ppn.  Not all hosts require a user name.
         If the server requires a password to complete the  login procedure,
         the user  program will ask  for the password  and turn  off echoing
         while you type it.  Not all hosts require a password.

LOGIN x  is a synonym for USER.

ACCT x   x is  an account  number.  Some  hosts may  require this  for their
         billing/accounting purposes.

XCWD x   x is a user name, as in the USER command, which will be used as the
         default directory for foreign  file specifiers; the effect  is like
         the ALIAS monitor command here.  The command name stands for change
         working directory.

ALIAS x  is a synonym for XCWD.

RETR x←y This command retrieves a file from the foreign host.  x is  a local
         file specifier,  and y  is a foreign  file specifier.   The foreign
         file y is copied to the local file x.  Current settings (or default
         values) are  used for  byte size and  representation type.   The x←
         string is eaten locally, and the RETR y part is transmitted  to the
         foreign host.

GET x←y  is a synonym for RETR.

TTY x    is a version of RETR which uses x as the remote file specifier, and
         types the retrieved file on the user's terminal.

STOR x→y STOR  means store,  and this  command is  the inverse  of  the RETR
         command.  A local file is copied to a foreign host.

SEND x→y is a synonym for STOR.

APPE x→y This command will append the  local file to the end of  the foreign
         file.

PICKUP   This command is used to resume an interruped multiple file transfer
         and is explained further below.

LPPN     This  command   sets  the  local   PPN  flag,  which   affects  the
         interpretation  of  single-pathname  transfer  commands;   see  the
         section on multiple file transfer, below.

RPPN     This  command  clears  the  local  PPN  flag,  which   affects  the
         interpretation  of  single-pathname  transfer  commands;   see  the
         section on multiple file transfer, below.  (The command name stands
         for remote PPN.)

MAIL x   x is a user ID (like our PPN).  Following this command you may type
         in a  message which  will be mailed  to the  specified user  at the
         foreign  host.   The  message  must  be  terminated  with   a  line
         containing only a period.  The  MAIL program (see Appendix 4)  is a
         better way to send network mail.

MLFL x→y In this case x is a  local file specifier, and y is a  foreign user
         ID.  The text of the specified file will be mailed to the specified
         user.

XSEN x   is like MAIL, but the message is sent to the remote user's terminal
         if s/he is logged in, like the SEND monitor command at  SAIL.  This
         command and the  two following ones are  only implemented at  a few
         network hosts.  The  SEND monitor command  uses this protocol  if a
         network destination is specified.

XSEM x   is  like XSEN  but mails  the message  instead if  the user  is not
         logged in, like SEND/YESMAIL here.

XMAS x   is  like  XSEN but  mails  the  message also,  whether  or  not the
         recipient is logged in, like SEND/MAIL here.

LIST x←y y is  a foreign pathname,  possibly including wildcard  terms.  The
         directory listing of the specified pathname is stored in  the local
         file x.

DIRECT   is a synonym for LIST.

NLST x←y is like  LIST, but the  listing returned is  guaranteed to  have no
         extraneous information  in it, simply  one full pathname  per line.
         This listing is intended to be read by programs rather than humans,
         but if you really want it...

HELP     This command  asks the foreign  FTP server to  send back  a message
         indicating what commands it takes, etc.

STAT x   If x  is omitted,  this command asks  the FTP  server to  send back
         information regarding the FTP connection, e.g., socket numbers.  If
         x is a directory name at  their host (like our PPN), it  lists that
         file  directory.    Note:  contrary   to  protocol,   most  servers
         (including ours) treat a STAT  with no argument as a request  for a
         listing of the directory specified in the USER or XCWD command.

DELE x   x is a  foreign file specifier.  The  specified file is  deleted at
         the foreign host.

RNFR x   x is a  foreign file specifier.  This  command is short  for rename
         from; it must be immediately followed by a RNTO.

RNTO x   x is  a foreign  file specifier.  This  command completes  the file
         rename  operation  started  by  RNFR.   (Some  hosts  accept  * for
         wildcard specification in these commands.)

QUOT x   x is  any character  string, which  should be  an FTP  command with
         arguments.  The string is sent as is over the FTP control link (see
         protocol, NIC 10596, for terms).  QUOT was included to allow you to
         execute commands which are as yet unimplemented here, or  which are
         nonstandard, specific to some  serving host.  It will be  of little
         use for those commands which require some special action by the FTP
         program at this end.

BYE      Terminate connections with the foreign host and quit.

QUIT     is a synonym for BYE.

DISC     is a synonym for BYE.

XIND x   x is a local file  specifier.  The file will be read  and processed
         as FTP commands.
                           Multiple File Transfer


The RETR and STOR commands have some provisions for more convenient transfer
of groups of  files when similar  names are used  at both ends.   The normal
format of the commands requires the user to specify two file names,  one for
our local file system and the other for the remote host's file  system.  Our
FTP knows enough about the  filename syntax for certain systems  (mainly the
PDP-10 systems: ITS,  TOPS-10, TOPS-20, and TENEX)  to be able to  extract a
local filename from a remote one.

If only one filename  is given in a RETR  or STOR command, it is  scanned to
determine both the  local and the  remote file specification.   Normally (in
local PPN mode),  the entire file specification  is sent to the  remote host
except for anything inside [square brackets],  which is taken to be  a local
SAIL PPN.  In remote  PPN mode, everything is  sent to the remote  host, and
your own login or alias PPN is used for the local file.  Here are  the rules
for determining the local file specification:

     1.  A "token" in these rules means a string of letters, digits, and the
     characters - and @.   An asterisk (*) may be  used alone as a  token to
     indicate wildcard file groups,  as explained below.  If talking  to one
     of the ITS systems at MIT (MIT-AI, MIT-ML, MIT-DMS, and MIT-MC)  then a
     period (.) which follows  a non-token character (space  or punctuation)
     is taken as the first character  of a token; such a token may  also end
     with a period.

     2.  If talking to one of  the ITS systems, then a single left  or right
     broket (< or >) may be used alone as a token, which will  be completely
     ignored.  Otherwise, a token enclosed in brokets is ignored.

     3.  One or more tokens separated by commas, enclosed in square brackets
     ([ and ]), are ignored in remote PPN mode, as explained above; in local
     PPN mode, there must be only one or two such tokens, and they must form
     a valid SAIL PRJ or PPN.

     4.  Any characters  following a semicolon  (;) are ignored,  except for
     the  ITS  systems,  for  which the  token  preceding  the  semicolon is
     ignored.

     5.  A token followed by a colon (:) is ignored.

     6.  A  single non-ignored token  is taken as  the local  filename.  Two
     such tokens separated by a period (.) or separated only by one  or more
     spaces are taken as the local filename and extension.  The characters -
     and @  in a token  are ignored, and  the token is  truncated to  six or
     three characters  for the local  filename or extension.   (The leftmost
     six or three characters are used.)  A period which is taken as  a token
     constituent,  when  talking to  an  ITS system,  is  ignored  for local
     purposes.  If two or more  non-token periods are used in  the filename,
     the token after the first period is taken as the extension,  and tokens
     after the remaining periods are ignored.

     7.  No punctuation characters may appear in the filename  string except
     the ones mentioned above.  Spaces may be used anywhere except  within a
     token.

The FTP program notifies the user whenever it determines the local file name
from the remote one in this way, and, in the case of RETR, checks to  see if
that file already exists  before writing it.  If  there is such a  file, the
user is told so and can choose from these options:

     Type <cr> to overwrite the file.

     Type <lf>  to overwrite the  file and to  suppress further  warnings of
     this kind for the remainder of the FTP connection.

     Type <alt> to abort the transfer.

     Type another filename to write a different local file.

If this syntax is used, the implied local device is DSK.  (Note  that device
field in the remote file specification is ignored for local file purposes.) 
To use a different device the local=remote syntax must be used.

A  local  filename  or extension  of  *  either in  an  explicit  local file
specification  or as  determined from  the remote  specification is  used to
request the  transfer of more  than one file  by a single  command. Wildcard
device or PPN  is not allowed.  If  an explicit local file  specification is
used, it should agree with the remote file specification in which components
are wild, e.g., the command

RETR *.EXT=<THEIRDIRECTORY>FILE.*

will store any file(s) retrieved with local filename FILE.EXT,  probably not
the desired  effect.  Note  also that an  explicit local  file specification
with no filename or extension implies *.*, so the command

RETR [PRJ,PRG]←REMOTE.FILE

will be treated  unnecessarily as a multiple  retrieve.  This will  work but
will involve unnecessary operations.  The desired effect can be  obtained in
local PPN mode simply by typing

RETR REMOTE.FILE[PRJ,PRG]

which will take the PPN as applying to the local output file, and  will send
only the filename and extension to the remote host.  In remote PPN  mode, it
is necessary to repeat the filename:

RETR REMOTE.FIL[PRJ,PRG]=REMOTE.FILE

There is no  corresponding local/remote switch  for device names,  which are
always considered remote.  Therefore, you must say, e.g.,

RETR UDP1:REMOTE.FIL←REMOTE.FILE

to avoid  causing a multiple  RETR.  The  TTY command can  be used  to avoid
having to repeat the filename for the specific case of device TTY.

In the case  of multiple STOR,  the selected files  are found in  the user's
local file directory and a  STOR operation is performed for each  file found
which matches the  template.  The remote  file specification is  scanned for
each operation and  the character * is  replaced wherever seen by  the local
filename  or extension.   (The first  * is  replaced by  the  local filename
unless the character . (or, for ITS hosts only, space) precedes it, in which
case the  local extension  is used.   A second  * is  replaced by  the local
extension.)   If  the end  of  the  specification line  is  seen  before any
replacement has  been done,  the local filename  and extension  are inserted
before the carriage return as if *.* had been seen there, so that  a command
like

STOR *.SAI=<DIRECTORY>

will work.  In this situation  the filename and extension will  be separated
by a space  for ITS hosts or  a dot otherwise.  No  great effort is  made to
ensure the syntactic correctness of the resulting remote file specification;
presumably the remote host will complain if necessary.

For a multiple RETR, the remote file specification is used exactly  as typed
in an NLST operation, the results  of which are saved by the FTP  program to
be used  in successive RETR  operations.  Note that  the string used  as the
NLST argument  starts immediately after  the =  or ←, if  any, or  after the
space terminating the  RETR or GET command  name.  In particular,  any extra
spaces will be  sent to the remote  host.  The remote file  specification in
the typed command  is not used to  determine local file names;  instead, the
rules above are applied to each remote file specification received  from the
NLST operation.  If an explicit  local filename or extension is  provided by
the  user, it  will  be used  instead of  the  one derived  from  the remote
filename, as in the command

GET *.TXT=<IGNORED>*.THIS-NAME-IS-REPLACED-BY-TXT-LOCALLY

Multiple RETR depends on the remote host implementing NLST.  At present this
command is implemented in both TENEX and ITS.  TOPS-10 systems vary in which
commands they  implement.  Other  systems may have  a filename  syntax which
does not follow the rules above, in which case none of the features  in this
section will work.

The PICKUP  command can  be used to  continue a  multiple transfer  which is
interrupted either by a transient network failure or by a user  error (e.g.,
attempt to write into a  protected file).  The command permits  the transfer
to be re-entered along with the (local) name and extension of the first file
actually to be transfered.

Suppose  that you  are  trying to  copy  a complete  directory  from another
system, let's say a TENEX, so you give the command

RETR <FOO>*.*

After several files have been retrieved, the connection is broken,  while in
the  middle  of  copying  <FOO>PARTIALLY.COPIED  into  PARTIA.COP   in  your
directory.  You re-establish the connection, and type

PICKUP PARTIA.COP

at which point you are invited to repeat the RETR command, which will ignore
all files presented by the  remote host until one comes along  which matches
the name PARTIA.COP, at which point it begins actually reading files.

If the multiple transfer is stopped because of an error which does not break
the network connection, so you can continue using the same FTP, you can give
the  PICKUP command  without a  filename argument,  in which  case  the last
filename for which a transfer was attempted is used.  Also, after the PICKUP
command, you can  just type <return> instead  of repeating the STOR  or RETR
command,  and  the last  such  command  given will  be  repeated.   The last
transfer must have been a multiple STOR or RETR.

If the PICKUP  command line ends with  <alt> instead of <return>,  the first
file transfered will be  the one after the one  in the argument (or  the one
after the one remembered from the aborted transfer).  This is useful for the
case of a transfer which  cannot be done because of a  protection violation,
when  you want  to continue  the multiple  transfer, skipping  the protected
file.  In a situation like that, you may not know the name of the first file
you want to transfer, but only the  name of the last file you don't  want to
transfer.

If a PICKUP command is given after a transfer which is not multiple  but for
which an implicit local filename was used, e.g.

RETR <FOO>FILENAME.EXTENSION

which implicitly  specifies FILENA.EXT  as the local  name, then  the PICKUP
command with no argument can be used to repeat the transfer.
                           One-line FTP transfers


The format  for using the  FTP command to  carry out a  transfer all  in one
command line is this:

FTP local ← {host} remote
FTP {host} remote → local
FTP local → {host} remote
FTP {host} remote ← local

The braces are really to be typed; they're not meta-symbols.   The direction
of the arrow indicates the direction of the transfer; the first two examples
retrieve files from  the remote host,  and the last  two store files  at the
remote host.  Therefore, the arrows may not be replaced with equal  signs as
in  the multi-command  syntax.   The pathnames  may include  *  for multiple
transfers.

Although there must  be an arrow,  either of the  pathnames may be  null, in
which case the other one will be  used for both ends as in the RETR  or STOR
commands with only one pathname.

Normally FTP will  attempt to do  the transfer in  IMAGE mode.  If  you want
ASCII mode transfer,  give the command as  above, but with FTP/A  instead of
just  FTP.  If  the remote  host  will not  accept the  specified  mode, the
transfer is aborted and you can try negotiating manually.

Other switches  can also  follow the FTP  command: /R  changes the  mode for
parsing a single pathname from LPPN  to RPPN; /T is like the TTY  command in
multi-command FTP: it types the specified remote file on your terminal.  (No
local pathname or arrow is used with /T.)

After doing  the transfer  successfully, FTP will  close the  connection and
exit.  So if you  want to do several transfer  commands, it pays to  use the
multi-command syntax.

The host specification inside the  braces can contain more than just  a host
name.  Many hosts require a login sequence before files can  be transferred;
the parameters for  this login are supplied  in the host  specification like
this:

{hostname/user/acct}

This can be abbreviated to  just {hostname/user} or {hostname}.  If  no acct
is given, no ACCT command will be sent; if no user is given, the commands

USER ANONYMOUS
PASS SAIL

will be sent.  These are the standard FTP guest login for Tenex systems.  If
you do include  a user name,  and the remote host  asks for a  password, you
will be asked to supply it with echoing off.

If you often  use a particular host-user-acct  combination, you may  want to
store the information online instead of typing it in each time.  To do this,
include in your OPTION.TXT file one or more lines of the form

FTP: {host/user/acct},{name:host/user/acct/pass},{host/user//pass}

As you see in the example, the format allowed in OPTION.TXT has  more fields
allowed than the one typed in  the command.  One difference is that  you can
include  a password,  if you  don't  mind taking  the risk  of  storing your
passwords online.  (You can have a password but no acct as shown in the last
host in the example.) Also, there is a "name" field which may begin the host
specification; if no name is given, the first field serves both as  name and
as host.  The way to refer to a stored host specification is to type {name↑}
in the monitor command line.  Note that this name must exactly match the one
in OPTION.TXT, except for the  case of letters.  (Normally, a host  name can
be abbreviated  to enough  letters to determine  it uniquely.)  For example,
suppose the  host SRI-KL can  be abbreviated SRI.   Then these  commands are
equivalent:

FTP ←{SRI/NICGUEST}<NETINFO>LIAISON.TXT
FTP ←{SRI-KL/NICGUEST}<NETINFO>LIAISON.TXT

but if your OPTION.TXT file contains the line

FTP:{SRI/NICGUEST}

your command must be {SRI↑} and not {SRI-KL↑}.